home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / comstr.exe / READ.ME < prev    next >
Text File  |  1992-12-01  |  13KB  |  390 lines
  1. Patrick Reilly
  2. CIS: 70274,161
  3.  
  4.     This file represents an upgrade for the older COMST1.ZIP. That file had
  5. problems. Besides being cryptic and only a streambuf-derived class, there
  6. was a bug in the combuf::extractc() method. This has been fixed in this
  7. version.
  8.     As an addition, I've included a 'wrapper' iostream-derived class for
  9. people not overly familiar with the C++ stream classes. I've included
  10. manipulators for setting protocol (baud, parity, etc). Also new is this
  11. readme file!
  12.  
  13. Description:
  14.  
  15. struct ComDef
  16. -------------------------------------------------------------------------
  17.  
  18.     This structure is used internally by combuf to keep track of who owns
  19.     what port, etc. In general, you can ignore it.
  20.  
  21. struct CommProtocol
  22. -------------------------------------------------------------------------
  23.  
  24.     This structure encapsulates all the protocol settings for a port: baud
  25.     rate, number of bits, parity, and stopbits. It is accepted as an argument
  26.     to combuf::setParams(), and exists mainly for people wanting to directly
  27.     play with combuf.
  28.  
  29. class combuf
  30. -------------------------------------------------------------------------
  31.  
  32.     This is the heart and sole of serial streaming. The combuf class is
  33.     derived from streambuf, and handles the intricacies of serial
  34.     communication.
  35.  
  36.     Methods
  37.     -------
  38.  
  39.     combuf( char *s, int i, int o )        constructor
  40.  
  41.         This sets up an unopen buffer (not attached to any serial port), with
  42.         the input buffer at s[0]..s[i-1], and the output buffer at
  43.         s[i]..s[i+o-1]. Unlike most streambufs, combuf actually uses two
  44.         seperate areas of its internal buffer - an input part, and an output
  45.         part. This is because you really don't want to mix the two: you want
  46.         input to be inserted by the serial port (and extracted by your code)
  47.         and output (inserted by your code) to be extracted by the serial port.
  48.  
  49.     combuf()                            constructor
  50.  
  51.         This sets up an unopen buffer with no internal buffer. Note that you
  52.         will not be able to use (open) this until a call is made to setbuf():
  53.         combuf requires an internal buffer (does not operate in unbuffered
  54.         mode).
  55.  
  56.     ~combuf()                            destructor
  57.  
  58.         Performs housekeeping (flush/close) and destroys the combuf.
  59.  
  60.     streambuf *setbuf( char *buf, int sz )
  61.  
  62.         Since combuf actually uses two areas of a buffer, this method just
  63.         calls setbuf( buf, sz/2, sz/2 ).
  64.  
  65.     combuf *setbuf( char *buf, int isz, int osz )
  66.  
  67.         This sets the internal buffer input area to buf[0]..buf[isz-1] and
  68.         the output area to buf[isz]..buf[isz+osz-1].
  69.  
  70.     int underflow()
  71.  
  72.         This method is called whenever you want to extract from the combuf
  73.         but the serial port hasn't put any data in it. It will wait the
  74.         timeout period for a char to appear: if so, everythings fine. If not,
  75.         returns EOF which will signal the owning stream to set an error flag.
  76.  
  77.     int do_sputn( char *s, int n )
  78.  
  79.         This method puts your output into the buffer and handles serial-
  80.         related issues (priming the pump) to make sure it gets sent.
  81.  
  82.     int overflow(int)
  83.  
  84.         Called whenever the internal buffer is full and you still want to
  85.         send characters. Flushes the buffer and puts the char in there. It
  86.         checks for timeout errors, and will return EOF if one occurs, which
  87.         will signal the owning stream to set an error flag.
  88.  
  89.     void setPort( int p )
  90.  
  91.         'Opens' a serial port for use. The port number (p) MUST be in the
  92.         range 0 (COM1) to 3 (COM4).
  93.  
  94.     void setTimeout( long t )
  95.  
  96.         Sets the timeout period to t, where t is in 1/100ths of a second.
  97.         Note that, though the argument is in 1/100ths of a second, the actual
  98.         resolution of the timeout timer is in +/- 55mSec. It always rounds
  99.         up, so setTimeout(1) will set timeout_ to 1, NOT 0.
  100.  
  101.     void setInterCharDelay( long t )
  102.  
  103.         Sets the intercharacter delay to t, where t is in 1/100ths of a
  104.         second. The intercharacter delay is the amount of time paused between
  105.         sending consecutive characters; for some systems (and many modems),
  106.         some delay is required between the chars.
  107.  
  108.     void setInterLineDelay( long t )
  109.  
  110.         Sets the interline delay to t, where t is in 1/100ths of a second.
  111.         The interline delay is the amount of time paused after sending a
  112.         carriage return (ascii 13). Some systems are line-oriented (ie they
  113.         buffer a line, then process it) and so require a delay after a line
  114.         is sent.
  115.  
  116.     void setOption( int bit )
  117.  
  118.         Sets options flags. Valid bits are: HW_HANDSHAKE (use hardware
  119.         handshaking: not currently implemented), SW_HANDSHAKE (use software
  120.         handshaking (XON/XOFF): not currently implemented), and WAITFORECHO
  121.         (pause after sending a char until its echo is received: not currently
  122.         implemented).
  123.  
  124.     void clearOption( int bit )
  125.  
  126.         Clears option flag (see setOption() for flags).
  127.  
  128.     void setBaud( long b )
  129.  
  130.         Sets the baud rate to b. Must be in the range 50 <= b <= 115200. Note
  131.         that the baud rate is changed ONLY if the port is open.
  132.  
  133.     void setParity( int p )
  134.  
  135.         Sets the parity to p (one of: combuf::none, combuf::odd, combuf::even).
  136.         Note that the port must be open for the parity to change.
  137.  
  138.     void setBits( int b )
  139.  
  140.         Sets the number of bits in the protocol: must be 6 <= b <= 8. Note the
  141.         port MUST be open for the bits to change.
  142.  
  143.     void setStopBits( int b )
  144.  
  145.         Sets the number of stop bits in the protocol: must be 1 <= b <= 2.
  146.         Note that the port MUST be open for the stop bits to change.
  147.  
  148.     void setParams( CommProtocol& p )
  149.  
  150.         Sets the baud, bits, parity, and stopbits as contained in p. Note that
  151.         the port MUST be open for the changes to occur.
  152.  
  153.     void assertDTR()
  154.  
  155.         If the port is open, asserts the DTR (Data Terminal Ready) signal.
  156.         THIS IS NOT DONE AUTOMATICALLY BY SETPORT()!  Note that a modem will
  157.         ignore you unless you assert DTR.
  158.  
  159.     void unassertDTR()
  160.  
  161.         If the port is open, unasserts the DTR signal. This will disable
  162.         communications with a modem (if it was off-hook, it will hang up).
  163.  
  164.     int status()
  165.  
  166.         If timeout, line, or modem errors have occured, they set an internal
  167.         status flag. Calling this method will return the status, then clear
  168.         it.
  169.  
  170.     int extractc()
  171.  
  172.         Used by the ISR (interrupt service routine) to get the next char to
  173.         be sent out the serial port.
  174.  
  175.     int insertc( int ch )
  176.  
  177.         Used by the ISR to insert ch (incoming byte) to the buffer.
  178.  
  179.     unsigned long timeToTicks( unsigned long t )
  180.  
  181.         Converts t (1/100ths of a second) to system ticks (18.2 per second).
  182.  
  183.     void assertToPort( int offs, int mask )
  184.  
  185.         Used internally by combuf to assert (set) bits to a port.
  186.  
  187.     void unassertToPort( int offs, int mask )
  188.  
  189.         Used internally by combuf to unassert (clear) bits to a port.
  190.  
  191.     void interrupt far handler0x0B(...)
  192.  
  193.         This is the ISR that services interrupts for COM2/4.
  194.  
  195.     void interrupt far handler0x0C(...)
  196.  
  197.         This is the ISR that services interrupts for COM1/3.
  198.  
  199.     void handleIRQ( int port, int cause, int data )
  200.  
  201.         This is the method that is called when an interrupt on the combuf's
  202.         port occurs.
  203.  
  204.     Members
  205.     -------
  206.  
  207.     ComDef def[4]
  208.  
  209.         Holds information for each port (COM1,2,3,4).
  210.  
  211.     enum ParityType { none, odd, even }
  212.  
  213.         Used for the argument to setParity().
  214.  
  215.     int offs_
  216.  
  217.         The offset into def for this combuf. If EOF, means this combuf is
  218.         closed. Otherwise (0..3) this combuf is open.
  219.  
  220.     int errFlags
  221.  
  222.         Holds error flags; returned/cleared by status().
  223.  
  224.     int options
  225.  
  226.         Holds the option flags. Bits are set with setOption() and cleared
  227.         with clearOption().
  228.  
  229.     int inSize
  230.  
  231.         Size of the input buffer.
  232.  
  233.     unsigned long timeout_
  234.  
  235.         Timeout time (in ticks).
  236.  
  237.     unsigned long ibdelay_
  238.  
  239.         Intercharacter delay time (in ticks).
  240.  
  241.     unsigned long ildelay_
  242.  
  243.         Interline delay time (in ticks).
  244.  
  245. class comstream
  246. -------------------------------------------------------------------------
  247.  
  248.     This class is derived from iostream and presents an iostream 'wrapper'
  249.     for combuf.
  250.  
  251.     Methods
  252.     -------
  253.  
  254.     comstream()                            constructor
  255.  
  256.         Initializes a comstream with no buffer. Note that you can't use
  257.         this stream until a call to rdbuf()->setbuf() is made.
  258.  
  259.     comstream( char *b, int i, int o )    constructor
  260.  
  261.         Initializes a comstream